读取心跳序列数据（HealthHeartbeatSeriesSample） PRO#

Scripting 应用通过全局函数 Health.queryHeartbeatSeriesSamples() 提供对 Apple Health 中心跳序列数据的访问。该数据代表 Apple Watch 在锻炼或静息状态下记录的一系列连续心跳间隔（R-R 间隔），可用于分析心律稳定性与频率变化。

每条记录提供该心跳序列的持续时间、心跳数量及元数据，但不包含原始的每次间隔时间值。

什么是 Heartbeat Series Sample？#

每个 HealthHeartbeatSeriesSample 对象包含以下字段：

• uuid：该样本的唯一标识符
• sampleType：样本类型（恒为 "heartbeatSeries"）
• startDate / endDate：记录该序列的时间范围
• count：该序列中记录的心跳次数
• metadata：可选的附加信息（如记录来源设备、应用等）

注意：此接口仅返回摘要信息，不包含每一次心跳的具体间隔值。

API 用法#

1Health.queryHeartbeatSeriesSamples(
2  options?: {
3    startDate?: Date
4    endDate?: Date
5    limit?: number
6    strictStartDate?: boolean
7    strictEndDate?: boolean
8    sortDescriptors?: Array<{
9      key: "startDate" | "endDate"
10      order?: "forward" | "reverse"
11    }>
12    requestPermissions?: HealthQuantityType[]
13  }
14): Promise<HealthHeartbeatSeriesSample[]>

参数说明#

示例：读取最近的心跳序列记录#

1const results = await Health.queryHeartbeatSeriesSamples({
2  startDate: new Date("2025-07-01T00:00:00"),
3  endDate: new Date("2025-07-05T00:00:00"),
4  limit: 10,
5  sortDescriptors: [{ key: "startDate", order: "reverse" }]
6})
7
8for (const sample of results) {
9  console.log("UUID:", sample.uuid)
10  console.log("开始时间：", sample.startDate)
11  console.log("结束时间：", sample.endDate)
12  console.log("心跳次数：", sample.count)
13  console.log("元数据：", sample.metadata)
14  console.log("---")
15}

数据说明与限制#

• 无法获取每一次心跳的具体间隔时间，仅可看到总次数和时间范围。

• 如需计算平均心率（BPM），可通过以下方式估算：

  1const duration = (sample.endDate.getTime() - sample.startDate.getTime()) / 1000
  2const avgBPM = (sample.count / duration) * 60

• 该 API 不包含间隔异常（如缺失数据、节律中断）信息。

小结#

读取心跳序列数据的流程如下：

1. 使用 Health.queryHeartbeatSeriesSamples() 方法进行查询；
2. 可按时间范围、排序或限制数量进行过滤；
3. 遍历返回的 HealthHeartbeatSeriesSample 数组；
4. 每个对象包含 startDate、endDate、count 和 metadata；
5. 可通过持续时间与总次数计算平均心率。

此 API 适用于分析 Apple Watch 记录的心跳追踪频率，可结合锻炼或其他健康数据进行综合评估。